MutableRealmInt

A MutableRealmInt is a mutable, Long-like, numeric quantity.

MutableRealmInts are most interesting as members of a managed RealmObject object in a synchronized Realm. When managed, the increment and decrement operators implement a conflict-free replicated data type: simultaneous increments and decrements from multiple distributed clients will be aggregated correctly. For instance, if the value of a counter field for the object representing a User named Fred is currently 0, then the following code, executed on two different devices, simultaneously, even if connected by a slow, unreliable network, will always cause the value of counter to eventually converge on the value 2.

realm.write {
     query<User>("name = $0", "Fred")
         .first()
         .find()!!
         .counter
         .increment(1)
}

Note that the set operator must be used with care. It will quash the effects of any prior calls to increment or decrement. Although the value of a MutableRealmInt will always converge across devices, the specific value on which it converges will depend on the actual order in which operations took place. Mixing set with increment and/or decrement is, therefore, not advised, unless fuzzy counting is acceptable.

MutableRealmInts cannot be primary keys.

MutableRealmInts cannot store null values. However, it is possible to declare nullable MutableRealmInt class members:

var counter: MutableRealmInteger? = null

A reference to a managed MutableRealmInt is subject to all of the constraints that apply to the model object from which it was obtained: It can only be mutated within a transaction and it becomes invalid if the Realm backing it is closed. Note that a reference to a managed MutableRealmInt retains a reference to the model object to which it belongs. For example in this code:

val counter: MutableRealmInt = realm.query<User>("user = $0", "Fred")
     .first()
     .find()!!
     .counter

the counter holds a reference to the User model object from which it was obtained. Neither can be GCed until all references to both are unreachable.

It is worth noting that sharing MutableRealmInts across RealmObjects results in different behaviors depending on whether the objects are managed. For example, in this code userA and userB are unmanaged instances:

val userA: User = ... // userA.counter = 42
val userB: User = ... // userB.counter = null
userB.counter = userA.counter // both now point to the same reference
userA.counter.increment()
println(userA.counter.get()) // 43
println(userB.counter.get()) // 43

The assignment is done by reference as expected. However, on managed objects it is done by value as is the case for all other Realm primitive types. This means that the last two lines in the code above will yield a different result in case userA and userB are managed objects:

managedUserA.counter.increment()
println(managedUserA.counter.get()) // 43
println(managedUserB.counter.get()) // 42

In addition to the API functions, MutableRealmInt is a subclass of Number. This allows users to convert the boxed values stored in the instance to other numeric types. Moreover, the class provides a set of operators and infix functions similar to the ones provided by Long:

• Unary prefix operators: unaryPlus, unaryMinus

• Increment and decrement operators: inc, dec

• Arithmetic operators: plus, minus, times, div, rem

• Equality operators: equals

• Comparison operators: compareTo

• Bitwise functions: shl, shr, ushr, and, or, xor, inv

Both binary operators and logic bitwise functions enforce conversion of the received value to Long for convenience so precision loss may occur when computing the result depending on the type of the received Number. Additionally, all these operators and infix functions do not mutate the instance on which they are executed. For example, calling counter.inc() will not modify counter but rather create a new, unmanagedMutableRealmInt with the updated value. The only operations that result in a mutated value are set, increment and decrement.